\chapter{Backends}
\label{chap:backends}

This chapter will walk through almost all the Bigtop backends which were
available when it was written.\footnote{Conf General is deprecated,
therefore
I omitted it.}  For each backend, I will list what it makes and what config
statements it understands.  The config
statements\index{bigtop!backend config statements}
are shown in tables.
The first column has the name that appears in tentmaker under `Config
Statements.'  The second column has the name used in the Bigtop language
-- in case you are using a text editor for updates.

Keep in mind that all backends honor
`No Gen'\index{no
gen@\verb+no_gen+}\index{bigtop!turn off backend} (a.k.a. \verb+no_gen+).
That statement tells bigtop not to invoke the backend, so it won't make
anything.  Use this when you are happy with what the backend made and
don't want to risk overwriting anything.  This is preferable to removing
-- or commenting out -- the backend statement, since backends register
keywords.  If the backend is never loaded, its unique keywords will
generate syntax errors.

In addition to `No Gen,' all backends, except SiteLook GantryDefault, allow
`Alternate Template'\index{alternate template}\index{bigtop!alternate template}
(a.k.a. \verb+template+).\index{template!bigtop backend alternate}
It allows you to
replace the hard coded generation template in the backend with
one of your choice.  To make this work, copy the template out of the
backend into a file on your disk.  Then edit it to suit yourself.
But, you must keep the BLOCKS from the original template, and you can't
expect them to receive additional data.  For those changes, you need
to implement your own backend.  There is a booklet in the Bigtop
distribution explaining how to do that.

For boolean\index{boolean!in bigtop and tentmaker}
values, a check mark in the tentmaker box is equivalent to
any true value in the bigtop file.  For hand editing, I use 1
to set the value or 0 to turn it off.  In the descriptions below, I
will use the term `check this' to indicate booleans -- thus I'm almost
assuming you are running tentmaker.

Here begins the litany of backends.

\section{CGI
Gantry\index{CGI!Gantry bigtop backend}\index{bigtop!backends!CGI Gantry}}

The CGI Gantry backend makes a CGI script for use in CGI or FastCGI
environments.  It can also make a stand alone server.  Its config
statements are in Table \ref{tab:cgigantrykeys}.

\begin{table}
\begin{center}
\begin{tabular}{l|l|l}
Tentmaker Keyword & Bigtop  & What to do with it \\
                  & Keyword \\
\hline
FastCGI           & \verb+fast_cgi+ &
    Makes the CGI script \\
& & work only with FastCGI      \\

Use Gantry::Conf  & \verb+gantry_conf+ &
    Check this if you use the \\
& & Conf Gantry backend \\

Build Server      & \verb+with_server+ &
    Check this, if you want a \\
& & stand alone server script. \\

Server Port       & \verb+server_port+ &
    Use this to change the \\
& & default port for the stand \\
& & alone server away from \\
& & 8080.  Users may override \\
& & this at the command line. \\

Generate Root Path & \verb+gen_root+ &
    Adds a default root   \\
& & config variable (often a \\
& & good thing). \\    

Database Flexibility & \verb+flex_db+ &
    Adds command line \\
& & options to app.server for \\
& & database connection info. \\
\end{tabular}
\end{center}
\caption{CGI Gantry backend keywords.}
\label{tab:cgigantrykeys}
\end{table}

\section{Conf
Gantry\index{Conf Gantry bigtop backend}\index{bigtop!backends!Conf Gantry}}

If you want to use Gantry::Conf,\index{Gantry::Conf!with bigtop}
use this backend.  It makes a text file
called \verb+docs/AppName.gantry.conf+, which has a Gantry::Conf instance
for the app.  The file is formatted for use with Config::General.  You can
immediately copy this file to /etc/gantry.d (or its moral equivalant), if your
/etc/gantry.conf has a wild card include for all conf files in that directory.
Alternatively, you could make a symbolic link, allowing bigtop to keep
regenerating the file without you having to copy it there by hand.

Other than No Gen and Alternate Template, this backend understands the
statements in Table \ref{tab:confgantrykeys}.

\begin{table}
\begin{center}
\begin{tabular}{l|l|l}
Tentmaker Keyword  & Bigtop  & What to do with it \\
                   & Keyword \\
\hline
Conf Instance      & \verb+instance+ &
    The Gantry::Conf instance \\
& & name for your app.  \\
Conf File          & \verb+conffile+ &
    Your master conf file name \\
& & if it isn't /etc/gantry.conf \\
Generate Root Path & \verb+gen_root+ &
    Adds a default root config     \\
& & variable (often a good \\
& & thing). \\    

\end{tabular}
\end{center}
\caption{Conf Gantry backend keywords.}
\label{tab:confgantrykeys}
\end{table}

\section{Control
Gantry\index{Control Gantry bigtop
backend}\index{bigtop!backends!Control Gantry}}

Control Gantry makes controllers for the app.  For each controller, there
are two pieces: the stub and the GEN module.  Edit the stub, the GEN
module is fair game for regeneration.  The backend's config statements
are in Table \ref{tab:controlgantrykeys}.

\begin{table}
\begin{center}
\begin{tabular}{l|l|l}
Tentmaker & Bigtop  & What to do with it \\
Keyword   & Keyword \\
\hline
Full Use  & \verb+full_use+ & Puts the engine and template \\
Statement &                 & engine information in the base \\
& & controller.  Usually you check \\
& & this box instead of the one in \\
& & the HttpdConf backend. \\

For use with & \verb+dbix+ & Check this if you are using \\
DBIx::Class  &             & DBIx::Class. \\
\end{tabular}
\end{center}
\caption{Control Gantry backend keywords.}
\label{tab:controlgantrykeys}
\end{table}

\section{HttpdConf
Gantry\index{HttpdConf Gantry bigtop
backend}\index{bigtop!backends!HttpdConf Gantry}}

HttpdConf Gantry makes a \verb+docs/httpd.conf+ file which can be included
directly into your Apache conf.  It config statements are in
Table \ref{tab:httpdconfgantrykeys}.

\begin{table}
\begin{center}
\begin{tabular}{l|l|l}
Tentmaker & Bigtop  & What to do with it \\
Keyword   & Keyword \\
\hline
Use          & \verb+gantry_conf+  & Use this if you are using the \\
Gantry::Conf &                     & Conf Gantry backend \\

Skip Config        & \verb+skip_config+ &
    Check this when you are using  \\
& & the Config General backend, so \\
& & this backend will not duplicate \\
& & config information in httpd.conf. \\
& & Don't use this if you are using \\
& & Gantry::Conf. \\

Full Use  & \verb+full_use+    & Puts the engine and template \\
Statement &                    & engine info in the httpd.conf \\
          &                    & Perl block. This is the default. \\
          &                    & Uncheck it (make it false) \\
          &                    & if you don't want it.   \\

Generate  & \verb+gen_root+ & Adds a default root config     \\
Root Path &                 & variable (usually useless). \\    

\end{tabular}
\end{center}
\caption{HttpdConf Gantry backend keywords.}
\label{tab:httpdconfgantrykeys}
\end{table}

\section{Init
Std\index{Init Std bigtop backend}\index{bigtop!backends!Init Std}}

Init Std is responsible for making the things that h2xs makes (except that
it does not make any code modules).  This includes README, Changes,
etc.

Everything this backend makes is a stub\footnote{and therefore not subject to
regeneration}, except MANIFEST.  By default, it will bring the MANIFEST
up to date every time you regenerate the app -- in the same way that
\verb+./Build manifest+ would.  Since there is only one file
subject to regeneration, check `No Gen' (a.k.a. \verb+no_gen+) to
stop MANIFEST updates.

\section{Model
GantryCDBI\index{Model GantryCDBI bigtop
backend}\index{bigtop!backends!Model GantryCDBI}}

Model GantryCDBI makes models for use with
Class::DBI::Sweet\index{Class::DBI::Sweet}.
Its special config statement is shown in Table \ref{tab:modelgantrycdbikeys}.
This is no longer our preferred ORM.  We now use DBIx::Class.

\begin{table}
\begin{center}
\begin{tabular}{l|l|l}
Tentmaker & Bigtop Keyword & What to do with it \\
Keyword   & & \\
\hline
Models  & \verb+model_base_class+ & Use this if you don't want \\
Inherit &                         & your models to inherit \\
From    &                         & directly from \\
        &                         & Gantry::Utils::CDBI.
\end{tabular}
\end{center}
\caption{Model GantryCDBI backend keywords.}
\label{tab:modelgantrycdbikeys}
\end{table}

\section{Model
GantryDBIxClass\index{Model GantryDBIxClass bigtop
backend}\index{bigtop!backends!Model GantryDBIxClass}}

Model GantryDBIxClass generates model modules for use with DBIx::Class.
Its special config statement is shown in
Table \ref{tab:modelgantrydbixclasskeys}.
Be sure to check the `For Use with DBIx::Class' (a.k.a. \verb+dbix 1+;)
on the Control Gantry backend.

\begin{table}
\begin{center}
\begin{tabular}{l|l|l}
Tentmaker & Bigtop Keyword & What to do with it \\
Keyword   & & \\
\hline
Models  & \verb+model_base_class+ & Use this if you don't want \\
Inherit &                         & your models to inherit \\
From    &                         & directly from \\
        &                         & Gantry::Utils::DBIxClass.
\end{tabular}
\end{center}
\caption{Model GantryDBIxClass backend keywords.}
\label{tab:modelgantrydbixclasskeys}
\end{table}

\section{SiteLook
GantryDefault\index{SiteLook GantryDefault bigtop
backend}\index{bigtop!backends!SiteLook GantryDefault}}

SiteLook GantryDefault makes the Template Toolkit wrapper for your app.
The only keyword it understands is in
Table \ref{tab:sitelookgantrydefaultkeys}.

\begin{table}
\begin{center}
\begin{tabular}{l|l|l}
Tentmaker & Bigtop Keyword & What to do with it \\
Keyword   & & \\
\hline
Gantry  & \verb+gantry_wrapper+ & Use this to specify a non- \\
Wrapper &                       & standard default wrapper.  \\
Path    &                       & The default is \\
        &                       & \verb+sample_wrapper.tt+ which \\
        &                       & ships with Gantry.  Refer to \\
        &                       & it, when writing your own. \\
\end{tabular}
\end{center}
\caption{SiteLook GantryDefault backend keywords.}
\label{tab:sitelookgantrydefaultkeys}
\end{table}

\section{SQL
MySQL\index{SQL!MySQL bigtop backend}\index{bigtop!backends!SQL MySQL}}

SQL MySQL makes \verb+docs/schema.mysql+ with the valid SQL statements
needed to make a MySQL database for your app.  You may use this with
the other SQL backends.

\section{SQL
Postgres\index{SQL!PostgreSQL bigtop
backend}\index{bigtop!backends!SQL Postgres}}

SQL Postgres makes \verb+docs/schema.postgres+ with the valid SQL statements
needed to make a PostgreSQL database for your app.  You may use this with
the other SQL backends.

\section{SQL
SQLite\index{SQL!SQLite!bigtop backend}\index{bigtop!backends!SQL SQLite}}

SQL SQLite makes \verb+docs/schema.sqlite+ with the valid SQL statements
needed to make an SQLite database for your app.  You may use this with
the other SQL backends.

\section*{Summary}

Now that you have seen what backends are available in Bigtop, you may
be itching to write your own.  There is a booklet in the Bigtop distribution
docs directory which explains how to do that.
Our tour of Bigtop continues in the remaining chapters of this book with
guides to tentmaker and Bigtop's full syntax.
